Rewarded

warning

This is the documentation for the Advanced API. Most developers should use our Simplified API (documented in Rewarded), which comes with several built-in features such as:

• Automatic ad loading
• Retries for failed requests
• Simplified lifecycle management

Only use the Advanced API if you need fine-grained control over the ad loading and presentation lifecycle.

The Advanced API provides direct access to individual Rewarded instances, giving you complete control over when and how ads are loaded and presented.

Rewarded ads (also known as rewarded video ads) are a fullscreen format, but unlike interstitials the user is incentivized to watch its entire duration (usually 30 seconds) in order to get an in-app reward, such as in-game currency, extra lives or hints to pass a level.

The OnEarnedReward callback will be triggered by the adapted network, signaling that you can give the user their reward. If the user decides to skip the ad, this callback will not be called.

Create a Rewarded instance

var rewarded = Rewarded.Create("<placement-id>");

Register ad callbacks

// Load Callbacks
rewarded.OnPrebiddingFinished += result => {
    Debug.Log("Rewarded ad client-side bidding finished!");
};

rewarded.OnLoaded += result => {
    Debug.Log("Rewarded ad loaded!");
};

rewarded.OnFailedToLoad += (error, result) => {
    Debug.Log($"Rewarded ad failed to load. Reason: {error.Message}");
};

// Show Callbacks
rewarded.OnShowed += () => {
    Debug.Log("Rewarded ad is being shown!");
};

rewarded.OnFailedToShow += error => {
    // If you need to resume your app's flow, make sure to do it here and in the OnDismissed callback
    Debug.Log($"Rewarded ad failed to show. Reason: {error.Message}");
};

rewarded.OnImpression += impressionData => {
    Debug.Log("Rewarded ad impression!");
};

rewarded.OnDismissed += () => {
    // If you need to resume your app's flow, make sure to do it here and in the OnFailedToShow callback
    Debug.Log("Rewarded ad dismissed! Resume gameplay");
};

// Reward Callback
rewarded.OnEarnedReward += () => {
    Debug.Log("Rewarded ad earned a reward!");
};

info

For information about handling callback threads using XMediatorMainThreadDispatcher please refer to Sanitize Callback Threads.

Load an ad

rewarded.Load();

Load an ad (with custom properties)

rewarded.Load(
    customProperties: new CustomProperties.Builder()
        .AddString("game_mode", "classic")
        .Build()
);

Show an ad

if (rewarded.IsReady()) {
    rewarded.Show("rewarded-ad-space");
}

Dispose an ad

rewarded.Dispose();

Complete example

RewardedTest.cs

using JetBrains.Annotations;
using UnityEngine;
using UnityEngine.UI;
using XMediator.Api;

namespace X3M.XMediatorTest.Scripts
{
    public class RewardedTest : MonoBehaviour
    {
        public Button CreateButton;
        public Button LoadButton;
        public Button ShowButton;

        [CanBeNull] private Rewarded _rewarded;

        private void Start()
        {
            CreateButton.onClick.AddListener(OnCreateClicked);
            LoadButton.onClick.AddListener(OnLoadClicked);
            ShowButton.onClick.AddListener(OnShowClicked);
        }

        private void OnDestroy()
        {
            // Dispose the rewarded at the end of its lifecycle
            _rewarded?.Dispose();
        }

        private void OnCreateClicked()
        {
            Log("Create button clicked.");

            // Dispose previous rewarded instance
            _rewarded?.Dispose();

            // Create a rewarded instance
            _rewarded = Rewarded.Create("<placement-id>");

            // Load Callbacks
            _rewarded.OnPrebiddingFinished += result => XMediatorMainThreadDispatcher.Enqueue(
                () => { Log("Rewarded ad client-side bidding finished!"); }
            );

            _rewarded.OnLoaded += result => XMediatorMainThreadDispatcher.Enqueue(
                () => { Log("Rewarded ad loaded!"); }
            );

            _rewarded.OnFailedToLoad += (error, result) => XMediatorMainThreadDispatcher.Enqueue(
                () => { Log($"Rewarded ad failed to load. Reason: {error.Message}"); }
            );

            // Show Callbacks
            _rewarded.OnShowed += () => { Log("Rewarded ad is being shown!"); };

            _rewarded.OnFailedToShow += error => { Log($"Rewarded ad failed to show. Reason: {error.Message}"); };

            _rewarded.OnImpression += impressionData => { Log("Rewarded ad impression!"); };

            _rewarded.OnDismissed += () => { Log("Rewarded ad dismissed! Resume gameplay"); };

            // Reward Callback
            _rewarded.OnEarnedReward += () => { Log("Rewarded ad earned a reward!"); };
        }

        private void OnLoadClicked()
        {
            Log("Load button clicked.");
            _rewarded?.Load();
        }

        private void OnShowClicked()
        {
            Log("Show button clicked.");
            if (_rewarded != null && _rewarded.IsReady())
            {
                _rewarded.Show("rewarded-ad-space");
            }
        }

        private static void Log(string message)
        {
            Debug.Log($"[RewardedTest] {message}");
        }
    }
}